@travetto/base

Base

Application phase management, environment config and common utilities for travetto applications.

Install: @travetto/base

npm install @travetto/base

Base is the foundation of all Travetto applications. It is intended to be a minimal application set, as well as support for commonly shared functionality. It has support for the following key areas:

• Application Manifest
• File Operations
• Resource Management
• Lifecycle Support
• Shutdown Management
• Standard Error Support
• General Utilities

Application Manifest

The framework provides basic environment information, e.g. in prod/test/dev. This is useful for runtime decisions. This is primarily used by the framework, but can prove useful to application developers as well. The information that is available is:

• env.prod- Determines if app is in prod mode. A boolean flag that should indicate a production run.
• env.name - The environment name. Will usually be one of dev, test, or prod. Can be anything that is passed in.
• env.profiles: Set<string> - Specific application profiles that have been activated. This is useful for indicating different configuration or run states.
• env.debug - Simple logging flag. This boolean flag will enable or disable logging at various levels. By default debug is on in non-prod.
• env.resources: string[] - Resource folders. Search paths for resolving resource requests via ResourceManager
• source.local: string[] - Local source folders for transpiling. Does not extend to installed modules.
• source.common: string[] - Common source folders for transpiling. Includes installed modules.
• hasProfile(p: string): boolean; - Test whether or not a profile is active.

File Operations

The framework does a fair amount of file system scanning to auto - load files. It also needs to have knowledge of what files are available. The framework provides a simple and performant functionality for recursively finding files. This functionality leverages regular expressions in lieu of glob pattern matching(this is to minimize overall code complexity).

A simple example of finding specific .config files in your codebase:

Code: Looking for all .config files with the prefix defined by svc

import * as fs from 'fs/promises';
import { PathUtil, ScanFs } from '@travetto/boot';

export async function processServiceConfigs(svc: string) {
  const svcConfigs = await ScanFs.scanDir({ testFile: f => new RegExp(`${svc}.*[.]config$/`).test(f) }, PathUtil.cwd);
  for (const conf of svcConfigs) {
    // Do work

    const contents = await fs.readFile(conf.module, 'utf8');
  }
}

Resource Management

Resource management, loading of files, and other assets at runtime is a common pattern that the ResourceManager encapsulates. It provides the ability to add additional search paths, as well as resolve resources by searching in all the registered paths.

Code: Finding Images

import { ResourceManager } from '@travetto/base';

/**
 * Find a single image, first one wins by resource path order
 */
export async function findSingleImage() {
  const imagePath = await ResourceManager.find('/images/asset.gif');
  return imagePath;
}

/**
 * Find all .gif files under the images folder
 */
export async function findAllImages() {
  const imagePaths = await ResourceManager.findAll(/[.]gif$/, 'images/');
  return imagePaths;
}

Lifecycle Support

During the lifecycle of an application, there is a need to handle different phases of execution. When executing a phase, the code will recursively find all phase.<phase>.ts files under node_modules/@travetto, and in the root of your project. The format of each phase handler is comprised of five main elements:

• The phase of execution, which is defined by the file name phase.<phase>.ts
  • The key of the handler to be referenced for dependency management.
• The list of dependent handlers that the current handler depends on, if any.
• The list of handlers that should be dependent on the current handler, if any.
• The actual functionality to execute

An example would be something like phase.init.ts in the Configuration module.

Code: Config phase init

/**
 * Initializes the config source
 */
export const init = {
  key: '@trv:config/init',
  before: ['@trv:registry/init'],
  async action(): Promise<void> {
    const { ConfigManager } = await import('../src/manager');
    await ConfigManager.init();
  }
};

Shutdown Management

Another key lifecycle is the process of shutting down. The framework provides centralized functionality for running operations on shutdown. Primarily used by the framework for cleanup operations, this provides a clean interface for registering shutdown handlers. The code overrides process.exit to properly handle SIGKILL and SIGINT, with a default threshold of 3 seconds. In the advent of a SIGTERM signal, the code exits immediately without any cleanup.

As a registered shutdown handler, you can do.

Code: Registering a shutdown handler

import { ShutdownManager } from '@travetto/base';

export function registerShutdownHandler() {
  ShutdownManager.onShutdown('handler-name', async () => {
    // Do important work, the framework will wait until all async
    //   operations are completed before finishing shutdown
  });
}

Standard Error Support

While the framework is 100 % compatible with standard Error instances, there are cases in which additional functionality is desired. Within the framework we use AppError (or its derivatives) to represent framework errors. This class is available for use in your own projects. Some of the additional benefits of using this class is enhanced error reporting, as well as better integration with other modules (e.g. the RESTful API module and HTTP status codes).

The AppError takes in a message, and an optional payload and / or error classification. The currently supported error classifications are:

• general - General purpose errors
• system - Synonym for general
• data - Data format, content, etc are incorrect. Generally correlated to bad input.
• permission - Operation failed due to lack of permissions
• auth - Operation failed due to lack of authentication
• missing - Resource was not found when requested
• timeout - Operation did not finish in a timely manner
• unavailable - Resource was unresponsive

Stacktrace

The built in stack filtering will remove duplicate or unnecessary lines, as well as filter out framework specific steps that do not aid in debugging. The final result should be a stack trace that is concise and clear.

From a test scenario:

Code: Tracking asynchronous behavior

import { StacktraceUtil } from '@travetto/base';

function inner3() {
  throw new Error('Uh oh');
}

async function inner2() {
  return await inner3();
}

async function inner1() {
  return await inner2();
}

async function test() {
  await inner1();
}

export function main() {
  process.on('unhandledRejection', (err: unknown) => {
    console.log(StacktraceUtil.simplifyStack(err as Error));
  });

  test();
}

Will produce the following stack trace:

Terminal: Stack trace from async errors

$ node @travetto/base/bin/main ./doc/stack-test.ts 

Error: Uh oh  
    at inner3 (./doc/stack-test.ts:4:9)  
    at inner2 (./doc/stack-test.ts:8:16)  
    at inner1 (./doc/stack-test.ts:12:16)  
    at test (./doc/stack-test.ts:16:9)  
    at Object.main (./doc/stack-test.ts:24:3)

The needed functionality cannot be loaded until init.action executes, and so must be required only at that time.

General Utilities

Simple functions for providing a minimal facsimile to lodash, but without all the weight. Currently Util includes:

• isPrimitive(el) determines if el is a string, boolean, number or RegExp
• isPlainObject(obj) determines if the obj is a simple object
• isFunction(o) determines if o is a simple Function
• isClass(o) determines if o is a class constructor
• isSimple(a) determines if a is a simple value
• deepAssign(a, b, mode ?) which allows for deep assignment of b onto a, the mode determines how aggressive the assignment is, and how flexible it is. mode can have any of the following values:
  • loose, which is the default is the most lenient. It will not error out, and overwrites will always happen
  • coerce, will attempt to force values from b to fit the types of a, and if it can't it will error out
  • strict, will error out if the types do not match
• uuid(len: number) generates a simple uuid for use within the application.

CLI - build

Terminal: Build usage

$ trv build --help

Usage:  build [options]

Options:
  -o, --output <output>  Output directory
  -q, --quiet            Quiet operation
  -h, --help             display help for command

This command line operation pre-compiles all of the application source code. You can target the output location as well, which is useful in conjunction with process.env.TRV_CACHE for relocating the compiled files.

CLI - clean

The module provides the ability to clear the compilation cache to handle any inconsistencies that may arise.

Terminal: Clean operation

$ trv clean --help

Usage:  clean [options]

Options:
  -q, --quiet  Quiet operation
  -h, --help   display help for command